3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Viewer Information and State

The 3D Viewer provides a number of functions that you can use to get and set information about a viewer object and to manage its states.

Q3ViewerGetVersion

You can use the Q3ViewerGetVersion function to get the version of the 3D Viewer.

MAC OS VERSION



 
OSErr Q3ViewerGetVersion (

                     unsigned long    *majorRevision,

                     unsigned long    *minorRevision);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetVersion(

                     unsigned long    *majorRevision,

                     unsigned long    *minorRevision);

PARAMETERS

majorRevision: On entry, a pointer to an unsigned long integer. On exit, that long integer is set to the major revision number of the 3D Viewer.
minorRevision: On entry, a pointer to an unsigned long integer. On exit, that long integer is set to the minor revision number of the 3D Viewer.

DESCRIPTION

The Q3ViewerGetVersion function returns, in the long integers pointed to by the majorRevision and minorRevision parameters, the major and minor revision numbers of the 3D Viewer installed in the current operating environment.

SPECIAL CONSIDERATIONS

The Q3ViewerGetVersion function is available only in versions 1.1 and later of the 3D Viewer.

Q3ViewerGetReleaseVersion

You can use the Q3ViewerGetReleaseVersion function to get the release version number of the 3D Viewer.

MAC OS VERSION



 
OSErr Q3ViewerGetReleaseVersion (unsigned long *releaseRevision);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetReleaseVersion (unsigned long *releaseRevision);

PARAMETERS

releaseRevision: On entry, a pointer to an unsigned long integer. On exit, that long integer is set to the release revision number of the 3D Viewer in 'vers' format.

DESCRIPTION

The Q3ViewerGetReleaseVersion function returns, in the long integer pointed to by the releaseRevision parameter, the release version number of the 3D Viewer installed in the current operating environment.

For release 1.5.1 the release version number is 0x01518000.

Q3ViewerGetView

You can use the Q3ViewerGetView function to get the view object associated with a viewer object.

MAC OS VERSION



 
TQ3ViewObject Q3ViewerGetView (TQ3ViewerObject theViewer);

WINDOWS VERSION



 
TQ3ViewObject Q3WinViewerGetView (TQ3ViewerObject viewer);

PARAMETER

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetView function returns, as its function result, the view object currently associated with the viewer specified by the theViewer parameter.

Q3ViewerRestoreView

You can use the Q3ViewerRestoreView function to restore the camera associated with a viewer object.

MAC OS VERSION



 
OSErr Q3ViewerRestoreView (TQ3ViewerObject theViewer);

WINDOWS VERSION



 
TQ3Status Q3WinViewerRestoreView (TQ3ViewerObject viewer);

PARAMETER

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerRestoreView function restores the camera settings of the viewer specified by the theViewer parameter to the original camera specified in the associated view hints object. If there is no view hints object associated with the specified viewer, Q3ViewerRestoreView creates a new default camera.

Q3ViewerRestoreView performs the same operations as the reset button in the controller strip.

Q3ViewerGetCameraCount

You can use the Q3ViewerGetCameraCount function to determine how many camera objects are currently associated with a viewer object.

MAC OS VERSION



 
OSErr Q3ViewerGetCameraCount (

                     TQ3ViewerObject    theViewer, 

                     unsigned long      *cnt);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetCameraCount (

                     TQ3ViewerObject    viewer,

                     unsigned long      *count );

PARAMETERS

theViewer: A viewer object.
cnt: On entry, a pointer to an unsigned long integer. On exit, that long integer is set to the number of camera objects associated with the specified viewer object.

DESCRIPTION

The Q3ViewerGetCameraCount function returns, in the unsigned long integer pointed to by the cnt parameter, the number of camera objects associated with the viewer object specified by the theViewer parameter. If there is no view hints object associated with that viewer object, then there are no camera associated with that viewer object and Q3ViewerGetCameraCount returns 0.

Q3ViewerGetCameraCount counts only cameras of type kQ3CameraViewAngleAspect .

SPECIAL CONSIDERATIONS

The Q3ViewerGetCameraCount function is available only in versions 1.1 and later of the 3D Viewer.

Q3ViewerSetCameraByNumber

You can use the Q3ViewerSetCameraByNumber function to set a viewer's camera to a camera specified by its index in the list of the viewer's cameras.

MAC OS VERSION



 
OSErr Q3ViewerSetCameraByNumber (

                     TQ3ViewerObject    theViewer, 

                     unsigned long      cameraNo);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetCameraNumber (

                     TQ3ViewerObject    viewer,

                     unsigned long      cameraNo );

PARAMETERS

theViewer: A viewer object.
cameraNo: The index of a camera in the list of cameras associated with the specified viewer object. This list is 1-based (that is, the first camera has the index 1). The value of this parameter must be less than or equal to the number returned by the Q3ViewerGetCameraCount function.

DESCRIPTION

The Q3ViewerSetCameraByNumber function sets the camera of the viewer object specified by the theViewer parameter to the camera whose index in the list of the viewer's cameras is cameraNo .

Q3ViewerSetCameraByNumber performs the same operations as the camera viewpoint pop-up menu in the controller strip.

SPECIAL CONSIDERATIONS

The Q3ViewerSetCameraByNumber function is available only in versions 1.1 and later of the 3D Viewer.

Q3ViewerSetCameraByView

You can use the Q3ViewerSetCameraByView function to set a camera to a predefined camera view.

MAC OS VERSION



 
OSErr Q3ViewerSetCameraByView (

                     TQ3ViewerObject        theViewer, 

                     TQ3ViewerCameraView    viewType);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetCameraView (

                     TQ3ViewerObject        viewer,

                     TQ3ViewerCameraView    viewType );

PARAMETERS

theViewer: A viewer object.
viewType: A camera view command. See "Camera View Commands" for a description of the available camera view commands.

DESCRIPTION

The Q3ViewerSetCameraByView function sets the camera of the viewer object specified by the theViewer parameter to the camera viewpoint specified by the viewType parameter. For instance, if the value of the viewType parameter is kQ3ViewerCameraTop , then Q3ViewerSetCameraByView sets the camera to a viewpoint that is directly above the model in the viewer object.

SPECIAL CONSIDERATIONS

The Q3ViewerSetCameraByView function is available only in versions 1.1 and later of the 3D Viewer.

Q3ViewerGetFlags

You can use the Q3ViewerGetFlags function to get the current viewer flags for a viewer object.

MAC OS VERSION



 
unsigned long Q3ViewerGetFlags (TQ3ViewerObject theViewer);

WINDOWS VERSION



 
unsigned long Q3WinViewerGetFlags (TQ3ViewerObject viewer);

PARAMETER

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetFlags function returns, as its function result, the current set of viewer flags for the viewer specified by the theViewer parameter.

Q3ViewerSetFlags

You can use the Q3ViewerSetFlags function to set the viewer flags for a viewer object.

MAC OS VERSION



 
OSErr Q3ViewerSetFlags (

                     TQ3ViewerObject    theViewer,

                     unsigned long      flags);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetFlags (

                     TQ3ViewerObject    viewer,

                     unsigned long      flags );

PARAMETERS

theViewer: A viewer object.
flags: A set of viewer flags. See "Viewer Flags" for a description of the constants you can use to set or clear individual viewer flags.

DESCRIPTION

The Q3ViewerSetFlags function sets the viewer flags associated with the viewer object specified by the theViewer parameter to the values passed in the flags parameter.

Any changes to a viewer's flags will not be visible until you call Q3ViewerDraw with the specified viewer object.

Q3ViewerGetBounds

You can use the Q3ViewerGetBounds function to get the rectangle that bounds a viewer's pane.

MAC OS VERSION



 
OSErr Q3ViewerGetBounds (

                     TQ3ViewerObject    theViewer,

                     Rect               *bounds);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetBounds (

                     TQ3ViewerObject    viewer,

                     RECT               *bounds );

PARAMETERS

theViewer: A viewer object.
bounds: On exit, the rectangle that bounds the pane currently associated with the specified viewer object.

DESCRIPTION

The Q3ViewerGetBounds function returns, through the bounds parameter, the rectangle that currently bounds the pane associated with the viewer object specified by the bounds parameter.

Q3ViewerSetBounds

You can use the Q3ViewerSetBounds function to set the rectangle that bounds a viewer's pane.

MAC OS VERSION



 
OSErr Q3ViewerSetBounds (

                     TQ3ViewerObject    theViewer,

                     Rect               *bounds);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetBounds (

                     TQ3ViewerObject    viewer,

                     RECT               *bounds );

PARAMETERS

theViewer: A viewer object.
bounds: The desired viewer pane for the specified viewer object. This rectangle is specified in window coordinates, where the origin (0, 0) is the upper-left corner of the window and values increase to the right and down the window.

DESCRIPTION

The Q3ViewerSetBounds function sets the bounds of the viewer pane of the viewer object specified by the theViewer parameter to the rectangle specified by the bounds parameter.

Any changes to a viewer's bounds will not be visible until you call Q3ViewerDraw with the specified viewer object.

Q3ViewerGetMininumDimension

You can use the Q3ViewerGetMininumDimension function to get the sides of the smallest rectangle that can contain the controller strip of a viewer object.

MAC OS VERSION



 
OSErr Q3ViewerGetMininumDimension (

                     TQ3ViewerObject    theViewer, 

                     unsigned long      *width, 

                     unsigned long      *height);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetMinimumDimension (

                     TQ3ViewerObject    viewer,

                     unsigned long      *width,

                     unsigned long      *height );

PARAMETERS

theViewer: A viewer object.
width: On exit, the width of the minimum viewer pane required to contain the entire contents of the controller strip.
height: On exit, the height of the minimum viewer pane required to contain the entire contents of the controller strip.

DESCRIPTION

The Q3ViewerGetMininumDimension function returns, in the width and height parameters, the width and height of the minimum viewer pane required to contain the entire contents of the controller strip associated with the viewer object specified by the theViewer parameter. If your application allows the viewer pane to be resized, you should ensure that it is not sized smaller than the dimensions returned by Q3ViewerGetMininumDimension ; otherwise, some of the buttons in the controller strip will be clipped.

SPECIAL CONSIDERATIONS

The Q3ViewerGetMininumDimension function is available only in versions 1.1 and later of the 3D Viewer.

Q3ViewerGetPort

You can use the Q3ViewerGetPort function to get the Macintosh graphics port associated with a viewer object. This function has no equivalent in the Windows environment.



 
CGrafPtr Q3ViewerGetPort (TQ3ViewerObject theViewer);

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetPort function returns, as its function result, a pointer to the port currently associated with the viewer object specified by the theViewer parameter. The returned pointer may be a a pointer to a color graphics port, a pointer to an offscreen graphics world, or the value NULL , indicating that no port is currently associated with the viewer object.

Q3ViewerSetPort

You can use the Q3ViewerSetPort function to set the graphics port associated with a viewer object. This function has no equivalent in the Windows environment.



 
OSErr Q3ViewerSetPort (TQ3ViewerObject theViewer, CGrafPtr port);

theViewer: A viewer object.
port: A pointer to a color graphics port that specifies the window with which the specified viewer is to be associated, or a pointer to an offscreen graphics world. You can also pass the value NULL in this parameter to indicate that port is to be associated with the viewer object.

DESCRIPTION

The Q3ViewerSetPort function sets the graphics port associated with the viewer object specified by the theViewer parameter to the port specified by the port parameter.

Q3ViewerGetGroup

You can use the Q3ViewerGetGroup function to get the group of objects currently associated with a viewer.

MAC OS VERSION



 
TQ3GroupObject Q3ViewerGetGroup (TQ3ViewerObject theViewer);

WINDOWS VERSION



 
TQ3GroupObject Q3WinViewerGetGroup (TQ3ViewerObject viewer);

PARAMETER

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetGroup function returns, as its function result, a reference to the group containing the objects currently associated with the viewer specified by the theViewer parameter. The reference count of that group is incremented. You should therefore dispose of the group when you have finished using it.

Q3ViewerUseGroup

You can use the Q3ViewerUseGroup function to set the group of objects associated with a viewer.

MAC OS VERSION



 
OSErr Q3ViewerUseGroup (

                     TQ3ViewerObject    theViewer,

                     TQ3GroupObject     group);

WINDOWS VERSION



 
TQ3Status Q3WinViewerUseGroup (

                     TQ3ViewerObject    viewer,

                     TQ3GroupObject     group );

PARAMETERS

theViewer: A viewer object.
group: A group.

DESCRIPTION

The Q3ViewerUseGroup function sets the group of objects associated with the viewer specified by the theViewer parameter to the group specified by the group parameter.

Q3ViewerGetState

You can use the Q3ViewerGetState function to get the current state of a viewer object.

MAC OS VERSION



 
unsigned long Q3ViewerGetState (TQ3ViewerObject theViewer);

WINDOWS VERSION



 
unsigned long Q3WinViewerGetState (TQ3ViewerObject viewer);

PARAMETER

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetState function returns a long integer that encodes information about the current state of the viewer object specified by the theViewer parameter. Bits of the returned long integer are addressed using these constants, which define the viewer state flags:



 
enum {

    kQ3ViewerEmpty                      = 0,

    kQ3ViewerHasModel                   = 1<<0,

    kQ3ViewerHasUndo                    = 1<<1

};

If Q3ViewerGetState returns the value kQ3ViewerEmpty , there is no image currently displayed by the specified viewer object. If Q3ViewerGetState returns the value kQ3ViewerHasModel , there is an image currently displayed by the specified viewer object. If Q3ViewerGetState returns the value kQ3ViewerHasUndo , the user has modified the camera state using the interactive controls. You can use this information to determine whether Edit menu commands such as Undo, Cut, Clear, and Copy should be enabled or disabled.

Q3ViewerGetUndoString

You can use the Q3ViewerGetUndoString function to get a string that describes the most recent user operation that can be undone.

MAC OS VERSION



 
Boolean Q3ViewerGetUndoString (

                     TQ3ViewerObject    theViewer,

                     char               *string,

                     unsigned long      *cnt);

WINDOWS VERSION



 
TQ3Boolean Q3WinViewerGetUndoString (

                     TQ3ViewerObject    viewer,

                     char               *string,

                     unsigned long      stringSize,

                     unsigned long      *actualSize );

PARAMETERS

theViewer: A viewer object.
string: On entry, a pointer to a buffer. On exit, the buffer is filled with a localized string that describes the most recent user operation in the specified viewer that can be undone. Note that this string does not contain the substring "Undo."
cnt: On entry, a pointer to an unsigned long integer that specifies the size, in bytes, of the buffer pointed to by the string parameter. On exit, that long integer is set to the number of bytes actually copied into that buffer.
stringSize: On entry, an unsigned long integer that specifies the size, in bytes, of the buffer pointed to by the string parameter.
actualSize: On exit, a pointer to a long integer that is set to the number of bytes actually copied into the buffer.

DESCRIPTION

The Q3ViewerGetUndoString function returns, through the string parameter, a localized string that describes the most recent user action in the viewer specified by the theViewer parameter that can be undone.

Q3ViewerGetUndoString also returns, as its function result, a Boolean value that indicates whether you can call the Q3ViewerUndo function to perform the undo operation (TRUE ) or not (FALSE ).

Typically, you'll use the string returned by Q3ViewerGetUndoString to generate the text for the Undo menu item in the Edit menu. Note, however, that the string returned through the string parameter does not contain the substring "Undo." You should get the appropriate substring (perhaps from a resource) and conjoin it with the string returned by Q3ViewerGetUndoString to construct the menu item text.

SPECIAL CONSIDERATIONS

The Q3ViewerGetUndoString function is available only in versions 1.1 and later of the 3D Viewer.

Q3ViewerGetPict

You can use the Q3ViewerGetPict function to get a Macintosh 'pict' representation of the image currently displayed by a viewer object. This function has no equivalent in the Windows environment.



 
PicHandle Q3ViewerGetPict (TQ3ViewerObject theViewer);

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetPict function returns, as its function result, a handle to a Macintosh 'pict' structure that contains a representation of the image currently displayed by the viewer object specified by the theViewer parameter. You should call DisposeHandle to dispose of the memory occupied by the pict when you're done using it.

Q3ViewerGetButtonRect

You can use the Q3ViewerGetButtonRect function to get the rectangle that encloses a viewer button.

MAC OS VERSION



 
OSErr Q3ViewerGetButtonRect (

                     TQ3ViewerObject    theViewer, 

                     unsigned long      button, 

                     Rect               *rect);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetButtonRect (

                     TQ3ViewerObject    viewer,

                     unsigned long      button,

                     RECT               *rectangle );

PARAMETERS

theViewer: A viewer object.
button: A button.
rect: On exit, the rectangle that enclosed the specified button in the specified viewer.

DESCRIPTION

The Q3ViewerGetButtonRect function returns, in the rect parameter, the rectangle that encloses the button specified by the button parameter in the viewer object specified by the theViewer parameter. You can use these constants to specify the button whose rectangle you want returned:



 
kQ3ViewerButtonCamera

kQ3ViewerButtonTruck

kQ3ViewerButtonOrbit

kQ3ViewerButtonZoom

kQ3ViewerButtonDolly

kQ3ViewerButtonReset

Q3ViewerGetCurrentButton

You can use the Q3ViewerGetCurrentButton function to get the active button of a viewer.

MAC OS VERSION



 
unsigned long Q3ViewerGetCurrentButton (TQ3ViewerObject theViewer);

WINDOWS VERSION



 
unsigned long Q3WinViewerGetCurrentButton (TQ3ViewerObject viewer);

PARAMETER

theViewer: A viewer object.

DESCRIPTION

The Q3ViewerGetCurrentButton function returns, as its function result, the active button of the viewer object specified by the theViewer parameter. Q3ViewerGetCurrentButton returns one of these constants:



 
kQ3ViewerButtonTruck

kQ3ViewerButtonOrbit

kQ3ViewerButtonZoom

kQ3ViewerButtonDolly

Q3ViewerSetCurrentButton

You can use the Q3ViewerSetCurrentButton function to set the active button of a viewer pane.

MAC OS VERSION



 
OSErr Q3ViewerSetCurrentButton (

                     TQ3ViewerObject    theViewer, 

                     unsigned long      button);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetCurrentButton (

                     TQ3ViewerObject    viewer,

                     unsigned long      button );

PARAMETERS

theViewer: A viewer object.
button: A button.

DESCRIPTION

The Q3ViewerSetCurrentButton function sets the active button of the viewer object specified by the theViewer parameter to the button specified by the button parameter. You can use these constants to specify a button:



 
kQ3ViewerButtonTruck

kQ3ViewerButtonOrbit

kQ3ViewerButtonZoom

kQ3ViewerButtonDolly

Q3ViewerGetDimension

You can use the Q3ViewerGetDimension function to get the current dimensions of the model space in a viewer's view hints object.

MAC OS VERSION



 
OSErr Q3ViewerGetDimension (

                     TQ3ViewerObject    theViewer, 

                     unsigned long      *width, 

                     unsigned long      *height);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetDimension (

                     TQ3ViewerObject    viewer,

                     unsigned long      *width,

                     unsigned long      *height );

PARAMETERS

theViewer: A viewer object.
width: On exit, the width of the pane of the specified viewer.
height: On exit, the height of the pane of the specified viewer.

DESCRIPTION

The Q3ViewerGetDimension function returns, in the width and height parameters, the current width and height of the model space in the view hints object associated with the viewer object specified by the theViewer parameter. If there is no such view hints object, Q3ViewerGetDimension returns the width and height of the viewer pane.

Q3ViewerSetDimension

You can use the Q3ViewerSetDimension function to set the current dimensions of the model space in a viewer's view hints object.

MAC OS VERSION



 
OSErr Q3ViewerSetDimension (

                     TQ3ViewerObject    theViewer,

                     unsigned long      width,

                     unsigned long      height);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetDimension (

                     TQ3ViewerObject    viewer,

                     unsigned long      width,

                     unsigned long      height );

PARAMETERS

theViewer: A viewer object.
width: The desired width of the pane of the specified viewer.
height: The desired height of the pane of the specified viewer.

DESCRIPTION

The Q3ViewerSetDimension function sets the width and height of the model space in the view hints object associated with the viewer object specified by the theViewer parameter to the values specified by the width and height parameters.

Q3ViewerGetBackgroundColor

You can use the Q3ViewerGetBackgroundColor function to get the background color of a viewer.

MAC OS VERSION



 
OSErr Q3ViewerGetBackgroundColor (

                     TQ3ViewerObject    theViewer, 

                     TQ3ColorARGB       *color);

WINDOWS VERSION



 
TQ3Status Q3WinViewerGetBackgroundColor (

                     TQ3ViewerObject    viewer,

                     TQ3ColorARGB       *color );

PARAMETERS

theViewer: A viewer object.
color: On exit, the current background color.

DESCRIPTION

The Q3ViewerGetBackgroundColor function returns, in the color parameter, the background color of the viewer specified by the theViewer parameter.

Q3ViewerSetBackgroundColor

You can use the Q3ViewerSetBackgroundColor function to set the background color of a viewer.

MAC OS VERSION



 
OSErr Q3ViewerSetBackgroundColor (

                     TQ3ViewerObject    theViewer, 

                     TQ3ColorARGB       *color);

WINDOWS VERSION



 
TQ3Status Q3WinViewerSetBackgroundColor (

                     TQ3ViewerObject    viewer,

                     TQ3ColorARGB       *color );

PARAMETERS

theViewer: A viewer object.
color: The desired background color.

DESCRIPTION

The Q3ViewerSetBackgroundColor function sets the background color of the viewer specified by the theViewer parameter to the color specified by the color parameter.